GitHub Actionsを使ってGitHubリポジトリをBacklogのGitリポジトリに同期してみた
2024.11.11リテールアプリ共創部@大阪の岩田です。
みなさんは普段Gitリポジトリのホスティング先として何を利用されていますか？個人的に業務でよく利用しているのはGitHubなのですが、他にもBacklogのGitリポジトリを利用したいケースもあると思います。両者を比較した場合、GitHubのメリットとしてGitHub Actions等の便利機能を利用できることが挙げられます。対してBacklogのGitリポジトリはBacklogの課題とGitのコミット履歴を紐づけられるというメリットがあり、課題管理にBacklogを利用しているプロジェクトにおいてはこれは大きなメリットと言えます。
上記のような各サービスのメリットを良いとこ取りするために、GitHubのリポジトリをメインで利用しつつ、Backlogにも同期するような構成を試してみました。
やってみる
手動でGitHubリポジトリとBacklogのリポジトリを同期するのは面倒なので、GitHub Actionsを使って自動で同期する構成を作ってみたいと思います。普段はGitHubのリポジトリをメインで利用しつつ、mainブランチの内容をBacklogに自動同期することで課題とコミットの関連性をBacklog上で可視化します。
BacklogにGitリポジトリを作成
まずBacklogにGitリポジトリを作成します。
作成できたらリポジトリの設定で「コミットと課題を連携する」にチェックを入れておきます。
続いてssh-keygenでSSHのキーペアを作成します。
作成した公開鍵はBacklogの個人設定 → SSH 公開鍵に登録しておきます。
秘密鍵は後ほどGitHubのSecretsに登録します。
GitHubにリポジトリ作成
続いてGitHubの方にもリポジトリを作成します。
後ほどGitHub Actionsから利用するので、BACKLOG_SSH_PRIVATE_KEYという名前でSecretsを作成し先ほど作成したBacklog用の秘密鍵を登録します。
開発にはGitHubのリポジトリをメインで利用するので、ローカル環境のリモートリポジトリにはGitHubのリポジトリを追加してローカル環境からpushできるように設定しておいてください。
GitHub Actionsのワークフロー作成
続いてGit Hub Actionsのワークフローを作成します。今回は以下のようなワークフローを作成しました。
name: Sync to Backlog
on:
push:
branches:
- main
jobs:
sync:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0 # TODO 要件に合わせて調整する
- name: Set up SSH key
uses: webfactory/ssh-[email protected]
with:
ssh-private-key: ${{ secrets.BACKLOG_SSH_PRIVATE_KEY }}
- name: Add Backlog remote
run: |
git remote add backlog <Backlog GitリポジトリのSSH URL>
- name: Push to Backlog
run: |
ssh-keyscan -H <backlogのスペースID>@<backlogのスペースID>.git.backlog.jp >> ~/.ssh/known_hosts
git push backlog
簡単にポイントを解説していきます。
まずCheckout repositoryの部分でGitHubリポジトリの中身をチェックアウトします。この際fetch-depthに0を指定しています。このパラメータは取得するコミットの数を指定するパラメータで、0を指定すると全てのコミットが取得されます。コミット履歴に比例して処理時間や必要なストレージ領域が大きくなっていくため本来は0以外の値を指定すべきなのですが、具体的な数値として何を指定すべきかは難しい問題です。例えば3を指定すると、直近4つ以上のコミットがGitHubからBacklogに同期されていなかった場合Backlogにpushする際 ! [remote rejected] main -> main (shallow update not allowed)というエラーが発生してpushに失敗していまいます。この記事は検証目的でリポジトリのサイズも大きくならないことが分かっているためfetch-depth: 0 としています。
次にSet up SSH keyのステップではwebfactory/[email protected]を使ってSecretsから秘密鍵を読み込みssh-agentを起動します。これにより環境変数SSH_AUTH_SOCKとSSH_AGENT_PIDが設定され、後続のステップでsshによるBacklogリポジトリへのアクセスが可能になります。
最後のPush to Backlogではまずssh-keyscanを実行し、~/.ssh/known_hostsにBacklogの公開鍵を登録します。この処理を実行しておかないとpush時にHost key verification failed.のエラーが発生してしまいます。ssh-keyscan が実行できたら、あとはgit pushでGitHubリポジトリの中身をBacklogに同期して処理完了です。
GitHub上でPRをマージしてBacklogの課題と紐づくことを確認してみる
ここまでで準備ができたので実際に同期処理が動作し、Backlog上で課題とコミットが紐づけられることを確認してみましょう。
まずBacklog上で課題を作成します。
続いてリポジトリ配下のファイルを更新&コミットします。この際上記BacklogのチケットのIDをコミットメッセージに含めます。
git commit
[feat/test3 f15648f] Backlogの課題 CM_IWATA_TMP-3 に対応
1 file changed, 1 insertion(+)
create mode 100644 REDME.md
※ README.mdをタイポしてREDME.mdになってますが気にしないでください...
変更がコミットできたらGitHubにpushしてPRを作成→マージまで行います。PRがmainブランチにマージされるとActionsが起動するのでログを確認してみましょう。
無事に処理完了しています。
最後にBacklog側も確認してみます。
Backlogの課題に自動でコメントが追加されていることがわかります。
BacklogのGitリポジトリ上でコミット履歴を確認すると、課題との紐づけまで確認できました。
これでGitHubとBacklog双方の良いとこ取りができそうです！
課題など
無事にGitHubリポジトリをBacklogのGitリポジトリに同期できました。実際にこの構成を採用する場合は以下のような点に注意が必要です。
fetch-depthはどの程度にするか？
前述の通りactions/checkout@v4のfetch-depthに0を指定すると全てのコミットが取得されるため、0は指定すべきでないでしょう。ではどうすれば良いのかと言うと案件特性やブランチ戦略にもよるので一概には言えないところです。個人的にはざっくり100ぐらいを指定してしまって、頻繁にmainブランチにPRをマージするようなブランチ戦略と合わせて運用するのが良いかなと思います。
BacklogのSSHキーがユーザー単位の設定になる
今回紹介した構成ではGitHub ActionsからBacklogにアクセスするためにSSHのキーペアを作成してBacklog側に公開鍵を登録しましたが、このSSHキーの登録はBacklogのユーザー単位の設定です。GitHub Actionsで利用するSSHキーを所持しているユーザーのアカウントが削除されたり、プロジェクトから抜けたりするとGitHub Actionsも動作しなくなってしまいます。担当者の異動や退職によってリポジトリの同期が動かなくなる可能性がある点には留意が必要です。
まとめ
GitHubリポジトリをBacklogのGitリポジトリに同期する構成を試してみました。
前述したような課題点はありますがGitHub → Backlogの同期に失敗してもシステムの利用者に直接的に迷惑がかかるわけではなく、一時的に開発者が困るだけなので、リスクを受容するという選択肢も十分アリだとは思います。
今度はBacklog → GitHubの構成も試してみたいと思います。
